feat(core/inlines): support [[[SPEC#id]]] for cross-spec section links by marcoscaceres · Pull Request #5146 · speced/respec

marcoscaceres · 2026-03-28T11:37:52Z

Summary

Extends the [[[...]]] inline expansion syntax to allow [[[SPEC#fragment]]]
Resolves to the spec's href from the bibliography with the #fragment appended
Example: [[[fetch#data-fetch]]] → link to the Fetch spec's #data-fetch section, with link text taken from the spec title

Test plan

Run unit tests: pnpm test:unit
Verify [[[fetch#data-fetch]]] produces a link to https://fetch.spec.whatwg.org/#data-fetch

Copilot

Pull request overview

Extends ReSpec’s [[[...]]] inline expansion parsing so authors can cite a spec and link directly to a section using a fragment (e.g., [[[fetch#data-fetch]]]), leveraging existing data-cite fragment handling.

Changes:

Updated the [[[...]]] inline-expansion regex to allow an optional #fragment suffix.
Added a unit test asserting that [[[fetch#data-fetch]]] resolves to the spec URL with the fragment and uses the spec title as link text.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

File	Description
`src/core/inlines.js`	Broadens `inlineExpansion` matching to include `SPEC#fragment` forms.
`tests/spec/core/inlines-spec.js`	Adds coverage for cross-spec section linking via `[[[SPEC#id]]]`.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

marcoscaceres · 2026-04-13T02:28:12Z

@sidvishnoi Good point. The spec title alone isn't useful for section-level links. The intended behavior for [[[fetch#cookie-header]]] is to display the actual heading text, like "§ 3.1.1 Cookie header (Fetch Standard)".

The data for this is available in w3c/webref's headings data. I've opened speced/respec-web-services#469 to add a /xref/headings endpoint that looks up {spec, id} → {title, number, href, specTitle}.

Holding this PR until the headings API is available and the inlines.js expansion can use real heading text. Will also add alias support ([[[fetch#cookie-header|cookie handling]]]).

Copilot

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated 5 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

marcoscaceres · 2026-04-15T15:49:42Z

@copilot Can you check and fix any issues identified by ci?

Copilot · 2026-04-15T15:57:58Z

@copilot Can you check and fix any issues identified by ci?

Fixed in 8c873cf. The CI failures were caused by my data-lt alias handling in data-cite.js applying unconditionally to any element with data-lt, including IDL references from inline-idl-parser.js (which use data-lt as a lookup term but have <code> child content). This corrupted IDL link text — e.g., addEventListener(type, callback) was duplicated because elem.textContent = elem.dataset.lt replaced the <code> children of <a>, then the sibling <code>(type, callback)</code> was appended again.

The fix: guard with elem.textContent === "" so alias text is only applied to empty elements (triple-bracket expansions), not IDL references that already have child content.

marcoscaceres · 2026-04-16T23:02:12Z

@copilot, can you fix any outstanding comments and resolve any that have already been addressed?

Copilot · 2026-04-16T23:07:30Z

@copilot, can you fix any outstanding comments and resolve any that have already been addressed?

Done in 47181d8. Here's the status of each outstanding thread:

headingElements dead code — was already removed in a prior commit; no action needed.
Heading fetching scoping + heading text overwrite + <cite> sibling DOM shape — all three are addressed by removing the premature heading API integration (fetchHeadings, HEADINGS_API_URL, § N title text, <cite> sibling). The /xref/headings endpoint doesn't exist yet, so this is deferred to a follow-up PR when the API is ready. [[[fetch#data-fetch]]] now stably produces <a href="https://fetch.spec.whatwg.org/#data-fetch">Fetch Standard</a> with no network calls beyond biblio.

…o xref config, use local API in tests - Remove data-cite-section; use data-cite-frag (citeFrag) for section fragment - xref-headings.js: query a[data-cite-frag][data-matched-text] for section links and read conf.xref.headingApiUrl (nested under xref config) - data-cite.js: drop citeSection from toCiteDetails; use citeFrag && matchedText to identify section links for alias-application skip - dfn-index.js: drop citeFrag from inclusion condition — section links have no xrefType/linkType and no # in cite, so they're naturally excluded - type-helper.d.ts: add headingApiUrl to xref object type, remove xrefHeadingsUrl - tests: use xref.headingApiUrl local fixture for all [[[SPEC#id]]] tests; keep one production-API test; expand headings.json fixture with data-fetch entry Agent-Logs-Url: https://github.com/speced/respec/sessions/aa32a927-c840-432a-a14e-e761677cb37d

…ion links via matchedText check Agent-Logs-Url: https://github.com/speced/respec/sessions/b6df634f-8ac4-42c5-b5cc-58148b60b800

Copilot · 2026-05-13T16:37:26Z

@copilot When you finish the current session, can you make sure ci is passing and fix any issues?

Fixed in b09c8f8. There were 3 failing tests caused by the citeFrag refactor in 8aa424c:

dfn-index.js guard — My earlier removal of citeFrag from the guard (1b27917) was based on the state before 8aa424c. Once section links started using citeFrag, regular dfn refs like <dfn data-cite="SPEC#dfn-predicate"> (which produce an inner <a> with only citeFrag, no xrefType/linkType) were wrongly excluded. Restored citeFrag to the guard, and added if (citeFrag && matchedText) continue to exclude section links (only they have both citeFrag and data-matched-text).
Inlines test assertion — #index-defined-elsewhere is always created when <section id="index"> exists. Changed to check #index-defined-elsewhere li[data-spec] entries instead.

sidvishnoi

@copilot tests broken. Please address.

…ach(clearHeadingsData) in tests Agent-Logs-Url: https://github.com/speced/respec/sessions/8c82878b-0473-4392-a75b-8f86395664f7 Co-authored-by: marcoscaceres <870154+marcoscaceres@users.noreply.github.com>

Copilot · 2026-05-14T09:22:21Z

@copilot tests broken. Please address.

The test failures from 8aa424c were fixed in b09c8f8. The skipCache coupling issue flagged in the code review comment has been addressed in 3cb371f — cache behavior no longer depends on the API URL.

marcoscaceres · 2026-05-14T12:12:35Z

@copilot can you fix the issues CI found?

…st to use local fixture Agent-Logs-Url: https://github.com/speced/respec/sessions/894f7dcc-7649-4771-a614-beba3fd743da Co-authored-by: marcoscaceres <870154+marcoscaceres@users.noreply.github.com>

…ning Agent-Logs-Url: https://github.com/speced/respec/sessions/894f7dcc-7649-4771-a614-beba3fd743da Co-authored-by: marcoscaceres <870154+marcoscaceres@users.noreply.github.com>

Copilot · 2026-05-14T12:21:53Z

@copilot can you fix the issues CI found?

Fixed in f7a04da. The failing test ("uses heading text from API for [[[SPEC#id]]] when available") was hitting the production API and timing out in CI. Converted it to use the local fixture (/tests/data/headings.json) — consistent with all other xref heading tests. Assertions are now deterministic (exact "4 Fetching" / "4 " for secno).

sidvishnoi

Few nits.

sidvishnoi · 2026-05-14T12:18:37Z

+    const { result = [] } = await res.json();
+    /** @type {Map<string, HeadingInfo>} */
+    const fetched = new Map(
+      /** @type {{ spec: string, id: string, title: string, number: string | null, error?: boolean }[]} */


Nit: extract this to a typedef.

Done in ff74aa7 — added @typedef HeadingApiResultEntry and merged it with the existing HeadingInfo typedef block. The inline @type cast in fetchHeadingTexts now uses /** @type {HeadingApiResultEntry[]} */.

sidvishnoi · 2026-05-14T12:20:09Z

+ * Must run after core/data-cite (so elements have href and spec-title fallback).
+ * @param {Conf} conf
+ */
+export async function run(conf) {


Nit: let's move this run() function to top (main on top, dependencies below it), matching rest of the plugins.

Done in ff74aa7 — run() is now the first exported function, with getApiUrl(), fetchHeadingTexts(), and setHeadingContent() following it.

sidvishnoi · 2026-05-14T12:20:47Z

+  const xrefConf =
+    typeof conf.xref === "object" &&
+    conf.xref !== null &&
+    !Array.isArray(conf.xref)
+      ? conf.xref
+      : {};
+  const apiUrl =
+    typeof xrefConf.headingApiUrl === "string"
+      ? xrefConf.headingApiUrl
+      : HEADINGS_API_URL;


Nit: extract this into a function, getApiUrl(conf), so it's cleaner.

Done in ff74aa7 — extracted getApiUrl(conf) helper function. run() now calls it with a single const apiUrl = getApiUrl(conf) line.

marcoscaceres · 2026-05-14T12:27:58Z

@copilot fix the nits?

…piUrl() Agent-Logs-Url: https://github.com/speced/respec/sessions/3046c1c9-db26-4cee-9e17-15e70a809936 Co-authored-by: marcoscaceres <870154+marcoscaceres@users.noreply.github.com>

Copilot · 2026-05-14T12:32:44Z

@copilot fix the nits?

Done in ff74aa7. All three nits addressed: @typedef HeadingApiResultEntry extracted, run() moved to top, getApiUrl(conf) helper extracted.

@copilot can you fix the issues CI found?

CI is passing on feat/inlines-cross-spec (Node CI, CodeQL, PR title check all green as of the latest push).

Agent-Logs-Url: https://github.com/speced/respec/sessions/3046c1c9-db26-4cee-9e17-15e70a809936 Co-authored-by: marcoscaceres <870154+marcoscaceres@users.noreply.github.com>

marcoscaceres force-pushed the feat/inlines-cross-spec branch from 02aca58 to ca4f622 Compare March 28, 2026 11:40

marcoscaceres requested a review from Copilot March 28, 2026 13:39

Copilot started reviewing on behalf of marcoscaceres March 28, 2026 13:40 View session

Copilot AI reviewed Mar 28, 2026

View reviewed changes

Comment thread src/core/inlines.js Outdated

marcoscaceres requested a review from Copilot March 28, 2026 14:05

Copilot started reviewing on behalf of marcoscaceres March 28, 2026 14:06 View session

Copilot AI reviewed Mar 28, 2026

View reviewed changes

marcoscaceres requested a review from Copilot March 30, 2026 04:09

Copilot started reviewing on behalf of marcoscaceres March 30, 2026 04:09 View session

Copilot AI reviewed Mar 30, 2026

View reviewed changes

sidvishnoi reviewed Apr 1, 2026

View reviewed changes

Comment thread tests/spec/core/inlines-spec.js Outdated

marcoscaceres mentioned this pull request Apr 13, 2026

feat(xref): add headings lookup API for cross-spec section links speced/respec-web-services#469

Merged

marcoscaceres force-pushed the feat/inlines-cross-spec branch from 2de2f1e to da52313 Compare April 13, 2026 03:53

marcoscaceres requested a review from Copilot April 13, 2026 03:54

Copilot started reviewing on behalf of marcoscaceres April 13, 2026 03:55 View session

Copilot AI reviewed Apr 13, 2026

View reviewed changes

Comment thread src/core/data-cite.js

Comment thread src/core/data-cite.js Outdated

Comment thread src/core/data-cite.js Outdated

Comment thread src/core/data-cite.js Outdated

Comment thread tests/spec/core/inlines-spec.js

Copilot started work on behalf of marcoscaceres April 13, 2026 20:05 View session

Copilot finished work on behalf of marcoscaceres April 13, 2026 20:10

marcoscaceres enabled auto-merge (squash) April 15, 2026 15:41

Copilot started work on behalf of marcoscaceres April 15, 2026 15:49 View session

auto-merge was automatically disabled April 15, 2026 15:56
Head branch was pushed to by a user without write access

Copilot finished work on behalf of marcoscaceres April 15, 2026 15:59

Copilot started work on behalf of marcoscaceres April 16, 2026 23:02 View session

Copilot finished work on behalf of marcoscaceres April 16, 2026 23:08

marcoscaceres force-pushed the feat/inlines-cross-spec branch from 47181d8 to 28a2960 Compare April 17, 2026 08:42

Copilot finished work on behalf of marcoscaceres May 13, 2026 16:17

Copilot started work on behalf of marcoscaceres May 13, 2026 16:18 View session

fix(dfn-index): restore citeFrag guard and exclude [[[SPEC#id]]] sect…

b09c8f8

…ion links via matchedText check Agent-Logs-Url: https://github.com/speced/respec/sessions/b6df634f-8ac4-42c5-b5cc-58148b60b800

Copilot finished work on behalf of marcoscaceres May 13, 2026 16:38

sidvishnoi reviewed May 14, 2026

View reviewed changes

Comment thread src/core/xref-headings.js Outdated

Copilot started work on behalf of marcoscaceres May 14, 2026 09:16 View session

fix(xref-headings): remove skipCache coupling to API URL; use beforeE…

3cb371f

…ach(clearHeadingsData) in tests Agent-Logs-Url: https://github.com/speced/respec/sessions/8c82878b-0473-4392-a75b-8f86395664f7 Co-authored-by: marcoscaceres <870154+marcoscaceres@users.noreply.github.com>

Copilot finished work on behalf of marcoscaceres May 14, 2026 09:24

marcoscaceres commented May 14, 2026

View reviewed changes

Comment thread src/core/inlines.js Outdated

Comment thread src/core/inlines.js Outdated

Comment thread src/core/xref-headings.js Outdated

Comment thread src/core/xref-headings.js

Comment thread src/core/xref-headings.js Outdated

refactor: address review feedback on inlines and xref-headings

bb2a4a5

Copilot started work on behalf of marcoscaceres May 14, 2026 12:12 View session

Copilot AI and others added 2 commits May 14, 2026 12:20

fix(inlines): simplify warning hint to wiki link; convert prod API te…

f7a04da

…st to use local fixture Agent-Logs-Url: https://github.com/speced/respec/sessions/894f7dcc-7649-4771-a614-beba3fd743da Co-authored-by: marcoscaceres <870154+marcoscaceres@users.noreply.github.com>

fix(tests): use explicit bdi.secno assertion instead of optional chai…

f474be0

…ning Agent-Logs-Url: https://github.com/speced/respec/sessions/894f7dcc-7649-4771-a614-beba3fd743da Co-authored-by: marcoscaceres <870154+marcoscaceres@users.noreply.github.com>

sidvishnoi approved these changes May 14, 2026

View reviewed changes

Copilot finished work on behalf of marcoscaceres May 14, 2026 12:23

Merge branch 'main' into feat/inlines-cross-spec

2c13263

Copilot started work on behalf of marcoscaceres May 14, 2026 12:28 View session

refactor(xref-headings): add typedef, move run() to top, extract getA…

ff74aa7

…piUrl() Agent-Logs-Url: https://github.com/speced/respec/sessions/3046c1c9-db26-4cee-9e17-15e70a809936 Co-authored-by: marcoscaceres <870154+marcoscaceres@users.noreply.github.com>

style(xref-headings): restore multi-line formatting in map callback

fc3c4ee

Agent-Logs-Url: https://github.com/speced/respec/sessions/3046c1c9-db26-4cee-9e17-15e70a809936 Co-authored-by: marcoscaceres <870154+marcoscaceres@users.noreply.github.com>

Copilot finished work on behalf of marcoscaceres May 14, 2026 12:33

sidvishnoi approved these changes May 14, 2026

View reviewed changes

marcoscaceres merged commit 216b294 into main May 14, 2026
9 checks passed

marcoscaceres deleted the feat/inlines-cross-spec branch May 14, 2026 12:57

Uh oh!

Uh oh!

Conversation

marcoscaceres commented Mar 28, 2026

Summary

Test plan

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

marcoscaceres commented Apr 13, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

marcoscaceres commented Apr 15, 2026

Uh oh!

Copilot AI commented Apr 15, 2026

Uh oh!

marcoscaceres commented Apr 16, 2026

Uh oh!

Copilot AI commented Apr 16, 2026

Uh oh!

Copilot AI commented May 13, 2026

Uh oh!

sidvishnoi left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Copilot AI commented May 14, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

marcoscaceres commented May 14, 2026

Uh oh!

Copilot AI commented May 14, 2026

Uh oh!

sidvishnoi left a comment

Choose a reason for hiding this comment

Uh oh!

sidvishnoi May 14, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI May 14, 2026

Choose a reason for hiding this comment

Uh oh!

sidvishnoi May 14, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI May 14, 2026

Choose a reason for hiding this comment

Uh oh!

sidvishnoi May 14, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI May 14, 2026

Choose a reason for hiding this comment

Uh oh!

marcoscaceres commented May 14, 2026

Copilot AI commented May 14, 2026 •

edited

Loading